//! # RustCloud 核心模块
//!
//! 本模块是 RustCloud 微服务框架的核心组件，提供了微服务架构中的基础数据结构、
//! 错误处理机制和核心抽象。主要包括：
//!
//! * 服务实例管理 - `ServiceInstance` 结构体和相关操作
//! * HTTP 请求/响应处理 - `Request` 和 `Response` 结构体
//! * 错误处理机制 - `ServiceError` 和 `ValidationError` 枚举
//! * 配置管理 - 各种配置结构体
//! * 环境过滤和服务发现支持
//!
//! # 使用示例
//!
//! ```rust
//! use rustcloud_core::{ServiceInstance, Request, Response};
//!
//! // 创建服务实例
//! let instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
//!
//! // 创建HTTP请求
//! let request = Request::new("user-service", "GET", "/api/users");
//!
//! // 创建HTTP响应
//! let response = Response::new(200);
//! ```
//!
//! # 特性
//!
//! * 完整的服务实例生命周期管理
//! * 强类型的错误处理机制
//! * 灵活的元数据和环境配置支持
//! * 序列化/反序列化支持
//! * 全面的验证机制

use std::collections::HashMap;
use std::fmt;
use serde::{Deserialize, Serialize};

/// 定义微服务核心抽象特征（trait）
pub mod traits;
/// 单元测试模块
pub mod tests;
/// 应用框架和构建器模块
pub mod application;
/// 统一配置管理模块
pub mod config_unified;
/// 配置向后兼容模块
pub mod config_compat;
/// 依赖注入模块
pub mod di;
/// 统一错误处理模块
pub mod error;
/// 认证相关工具模块
#[cfg(feature = "auth-tools")]
pub mod auth;
/// HTTP 客户端工具模块
#[cfg(feature = "http-tools")]
pub mod http_client;
/// 配置构建器工具模块
#[cfg(feature = "config-tools")]
pub mod config_builder;

// 重新导出核心特征和应用框架
pub use traits::*;
pub use application::*;
/// 重新导出统一配置管理
pub use config_unified::*;
/// 重新导出向后兼容配置（优先级更高）
pub use config_compat::*;
/// 重新导出统一错误处理
pub use error::*;
/// 重新导出认证工具（可选，避免破坏现有API）
#[cfg(feature = "auth-tools")]
pub use auth::*;
/// 重新导出HTTP客户端工具
#[cfg(feature = "http-tools")]
pub use http_client::*;
/// 重新导出配置构建器工具
#[cfg(feature = "config-tools")]
pub use config_builder::*;

/// 服务实例数据结构
///
/// 表示一个在服务注册中心注册的微服务实例。该结构体包含了服务发现、
/// 负载均衡和健康检查所需的所有信息。
///
/// # 字段说明
///
/// * `service_id` - 服务实例的唯一标识符，通常为服务名称
/// * `host` - 服务实例的主机地址，支持 IPv4、IPv6 和域名
/// * `port` - 服务实例的端口号，范围为 1-65535
/// * `scheme` - 服务实例使用的协议（http、https、grpc、tcp、udp）
/// * `metadata` - 服务实例的元数据信息，如版本号、环境标签等
/// * `healthy` - 服务实例的健康状态，用于健康检查
/// * `weight` - 服务实例的权重，用于加权负载均衡，必须大于 0
/// * `group` - 服务分组，用于逃辑服务管理
/// * `namespace` - 命名空间，用于环境隔离
/// * `environment` - 环境标识（dev/test/staging/prod等）
/// * `cluster` - 集群名称，用于多集群部署
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::ServiceInstance;
/// use std::collections::HashMap;
///
/// // 创建基本服务实例
/// let mut instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
///
/// // 添加元数据
/// instance.add_metadata("version", "1.0.0");
/// instance.add_metadata("region", "us-west-1");
///
/// // 设置权重
/// instance.set_weight(2.0).unwrap();
///
/// // 设置健康状态
/// instance.set_healthy(true);
///
/// // 验证实例
/// assert!(instance.validate().is_ok());
/// ```
///
/// # 注意事项
///
/// * 所有字段都会在 `validate()` 方法中进行验证
/// * 权重必须大于 0，否则会返回错误
/// * 支持序列化和反序列化，可用于网络传输和持久化
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ServiceInstance {
    /// 服务实例的唯一标识符
    pub service_id: String,
    /// 服务实例的主机地址（IPv4/IPv6地址或域名）
    pub host: String,
    /// 服务实例的端口号（1-65535）
    pub port: u16,
    /// 服务实例使用的协议（http/https/grpc等）
    pub scheme: String,
    /// 服务实例的元数据信息（版本、环境标签等）
    pub metadata: HashMap<String, String>,
    /// 服务实例的健康状态
    pub healthy: bool,
    /// 服务实例的权重（用于负载均衡）
    pub weight: f64,
    /// 服务分组（可选）
    pub group: Option<String>,
    /// 命名空间（可选）
    pub namespace: Option<String>,
    /// 环境标识（dev/test/staging/prod等）
    pub environment: Option<String>,
    /// 集群名称（可选）
    pub cluster: Option<String>,
}

impl ServiceInstance {
    /// 创建一个新的服务实例
    /// 
    /// # 参数
    /// * `service_id` - 服务实例的唯一标识符
    /// * `host` - 服务实例的主机地址
    /// * `port` - 服务实例的端口号
    /// * `scheme` - 服务实例使用的协议
    /// 
    /// # 示例
    /// ```
    /// use rustcloud_core::ServiceInstance;
    /// let instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
    /// ```
    pub fn new(service_id: impl Into<String>, host: impl Into<String>, port: u16, scheme: impl Into<String>) -> Self {
        Self {
            service_id: service_id.into(),
            host: host.into(),
            port,
            scheme: scheme.into(),
            metadata: HashMap::new(),
            healthy: true,
            weight: 1.0,
            group: None,
            namespace: None,
            environment: None,
            cluster: None,
        }
    }
    
    /// 创建一个带分组和环境信息的服务实例
    /// 
    /// 该方法提供了更完整的服务实例创建方式，支持设置分组、命名空间和环境信息。
    /// 这对于复杂的微服务架构非常有用，可以实现环境隔离和服务分组。
    ///
    /// # 参数
    ///
    /// * `service_id` - 服务实例的唯一标识符
    /// * `host` - 服务实例的主机地址
    /// * `port` - 服务实例的端口号
    /// * `scheme` - 服务实例使用的协议
    /// * `group` - 服务分组（可选）
    /// * `namespace` - 命名空间（可选）
    /// * `environment` - 环境标识（可选）
    ///
    /// # 返回值
    ///
    /// 返回一个新的 `ServiceInstance` 实例，包含指定的分组和环境信息。
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceInstance;
    ///
    /// let instance = ServiceInstance::with_group_and_env(
    ///     "user-service",
    ///     "192.168.1.100",
    ///     8080,
    ///     "https",
    ///     Some("user-group".to_string()),
    ///     Some("production".to_string()),
    ///     Some("prod".to_string()),
    /// );
    ///
    /// assert_eq!(instance.group, Some("user-group".to_string()));
    /// assert_eq!(instance.namespace, Some("production".to_string()));
    /// assert_eq!(instance.environment, Some("prod".to_string()));
    /// ```
    pub fn with_group_and_env(
        service_id: impl Into<String>, 
        host: impl Into<String>, 
        port: u16, 
        scheme: impl Into<String>,
        group: Option<String>,
        namespace: Option<String>,
        environment: Option<String>,
    ) -> Self {
        Self {
            service_id: service_id.into(),
            host: host.into(),
            port,
            scheme: scheme.into(),
            metadata: HashMap::new(),
            healthy: true,
            weight: 1.0,
            group,
            namespace,
            environment,
            cluster: None,
        }
    }

    /// 生成服务的完整地址字符串
    /// 格式为：scheme://host:port
    /// 
    /// # 示例
    /// ```
    /// use rustcloud_core::ServiceInstance;
    /// let instance = ServiceInstance::new("service", "127.0.0.1", 8080, "http");
    /// assert_eq!(instance.address(), "http://127.0.0.1:8080");
    /// ```
    pub fn address(&self) -> String {
        format!("{}://{}:{}", self.scheme, self.host, self.port)
    }

    /// 验证服务实例的所有字段是否有效
    /// 
    /// 这是一个综合性的验证方法，会检查服务实例的所有关键字段是否符合规范。
    /// 包括服务ID、主机地址、端口号、协议和权重的有效性检查。
    ///
    /// # 验证规则
    ///
    /// * **服务ID**: 不能为空字符串
    /// * **主机地址**: 不能为空，必须是有效的 IPv4、IPv6 地址或域名
    /// * **端口号**: 不能为 0，必须在 1-65535 范围内
    /// * **协议**: 不能为空，必须是支持的协议（http/https/grpc/tcp/udp）
    /// * **权重**: 必须大于 0
    ///
    /// # 返回值
    ///
    /// * `Ok(())` - 所有字段都有效
    /// * `Err(ValidationError)` - 包含具体错误信息的验证错误
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceInstance;
    ///
    /// let instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
    /// assert!(instance.validate().is_ok());
    ///
    /// let invalid_instance = ServiceInstance::new("", "127.0.0.1", 8080, "http");
    /// assert!(invalid_instance.validate().is_err());
    /// ```
    ///
    /// # 错误类型
    ///
    /// * `ValidationError::InvalidServiceId` - 服务ID无效
    /// * `ValidationError::InvalidHost` - 主机地址无效
    /// * `ValidationError::InvalidPort` - 端口号无效
    /// * `ValidationError::InvalidScheme` - 协议无效
    /// * `ValidationError::InvalidWeight` - 权重无效
    pub fn validate(&self) -> Result<(), ValidationError> {
        if self.service_id.trim().is_empty() {
            return Err(ValidationError::InvalidServiceId("服务ID不能为空".to_string()));
        }

        if self.host.trim().is_empty() {
            return Err(ValidationError::InvalidHost("主机地址不能为空".to_string()));
        }

        // 验证主机地址格式（IPv4、IPv6或域名）
        if !self.is_valid_host(&self.host) {
            return Err(ValidationError::InvalidHost(format!("无效的主机地址: {}", self.host)));
        }

        if self.port == 0 {
            return Err(ValidationError::InvalidPort("端口号不能为0".to_string()));
        }

        if self.scheme.trim().is_empty() {
            return Err(ValidationError::InvalidScheme("协议不能为空".to_string()));
        }

        // 验证协议格式
        if !matches!(self.scheme.as_str(), "http" | "https" | "grpc" | "tcp" | "udp") {
            return Err(ValidationError::InvalidScheme(format!("不支持的协议: {}", self.scheme)));
        }

        if self.weight <= 0.0 {
            return Err(ValidationError::InvalidWeight("权重必须大于0".to_string()));
        }

        Ok(())
    }

    /// 验证主机地址格式
    /// 
    /// 该方法用于验证主机地址是否为有效的 IPv4、IPv6 地址或域名。
    /// 这是一个内部辅助方法，由 `validate()` 方法调用。
    ///
    /// # 参数
    ///
    /// * `host` - 需要验证的主机地址字符串
    ///
    /// # 返回值
    ///
    /// * `true` - 主机地址有效
    /// * `false` - 主机地址无效
    ///
    /// # 支持的地址格式
    ///
    /// * IPv4 地址：192.168.1.1
    /// * IPv6 地址：::1, 2001:db8::1
    /// * 域名：example.com, api.example.com
    fn is_valid_host(&self, host: &str) -> bool {
        // 检查是否为IPv4地址
        if host.parse::<std::net::Ipv4Addr>().is_ok() {
            return true;
        }

        // 检查是否为IPv6地址
        if host.parse::<std::net::Ipv6Addr>().is_ok() {
            return true;
        }

        // 检查是否为域名（基础验证）
        let host = host.trim();
        !host.is_empty() && host.chars().all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '.' || c == '_')
    }

    /// 添加元数据信息
    /// 
    /// 元数据用于存储服务实例的附加信息，如版本号、区域信息、环境标签等。
    /// 这些信息可以用于服务路由、负载均衡策略和监控统计。
    ///
    /// # 参数
    ///
    /// * `key` - 元数据的键名，建议使用统一的命名规范
    /// * `value` - 元数据的值，支持任意字符串
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceInstance;
    ///
    /// let mut instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
    /// 
    /// // 添加版本信息
    /// instance.add_metadata("version", "1.2.3");
    /// 
    /// // 添加区域信息
    /// instance.add_metadata("region", "us-west-1");
    /// 
    /// // 添加环境标签
    /// instance.add_metadata("env", "production");
    /// 
    /// // 添加自定义标签
    /// instance.add_metadata("team", "backend");
    /// ```
    ///
    /// # 常用元数据键名
    ///
    /// * `version` - 服务版本号
    /// * `region` - 部署区域
    /// * `zone` - 可用区
    /// * `env` - 环境类型
    /// * `team` - 负责团队
    /// * `protocol_version` - 协议版本
    pub fn add_metadata(&mut self, key: impl Into<String>, value: impl Into<String>) {
        self.metadata.insert(key.into(), value.into());
    }

    /// 获取元数据信息
    /// 
    /// 根据指定的键名获取相应的元数据值。如果键名不存在，则返回 None。
    ///
    /// # 参数
    ///
    /// * `key` - 需要查询的元数据键名
    ///
    /// # 返回值
    ///
    /// * `Some(&str)` - 找到对应的元数据值
    /// * `None` - 指定的键名不存在
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceInstance;
    ///
    /// let mut instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
    /// instance.add_metadata("version", "1.2.3");
    /// 
    /// // 获取存在的元数据
    /// assert_eq!(instance.get_metadata("version"), Some("1.2.3"));
    /// 
    /// // 获取不存在的元数据
    /// assert_eq!(instance.get_metadata("nonexistent"), None);
    /// ```
    pub fn get_metadata(&self, key: &str) -> Option<&str> {
        self.metadata.get(key).map(|s| s.as_str())
    }

    /// 设置服务实例权重
    /// 
    /// 权重用于加权负载均衡算法，权重越高的实例将会接收更多的请求。
    /// 权重必须为正数，否则会返回验证错误。
    ///
    /// # 参数
    ///
    /// * `weight` - 新的权重值，必须大于 0
    ///
    /// # 返回值
    ///
    /// * `Ok(())` - 权重设置成功
    /// * `Err(ValidationError::InvalidWeight)` - 权重值无效（小于或等于 0）
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceInstance;
    ///
    /// let mut instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
    /// 
    /// // 设置正常权重
    /// assert!(instance.set_weight(2.5).is_ok());
    /// assert_eq!(instance.weight, 2.5);
    /// 
    /// // 试图设置无效权重
    /// assert!(instance.set_weight(0.0).is_err());
    /// assert!(instance.set_weight(-1.0).is_err());
    /// ```
    pub fn set_weight(&mut self, weight: f64) -> Result<(), ValidationError> {
        if weight <= 0.0 {
            return Err(ValidationError::InvalidWeight("权重必须大于0".to_string()));
        }
        self.weight = weight;
        Ok(())
    }
    
    /// 链式设置权重方法
    /// 
    /// 这是一个链式调用方法，允许在创建服务实例后立即设置权重。
    /// 与 `set_weight` 不同，该方法会消耗并返回 `self`，适合用于方法链调用。
    ///
    /// # 参数
    ///
    /// * `weight` - 新的权重值，必须大于 0
    ///
    /// # 返回值
    ///
    /// * `Ok(Self)` - 返回设置了新权重的服务实例
    /// * `Err(ValidationError::InvalidWeight)` - 权重值无效
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceInstance;
    ///
    /// // 链式调用创建带权重的服务实例
    /// let instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http")
    ///     .with_weight(2.5)
    ///     .expect("权重设置失败");
    /// 
    /// assert_eq!(instance.weight, 2.5);
    /// 
    /// // 无效权重会返回错误
    /// let result = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http")
    ///     .with_weight(-1.0);
    /// assert!(result.is_err());
    /// ```
    pub fn with_weight(mut self, weight: f64) -> Result<Self, ValidationError> {
        if weight <= 0.0 {
            return Err(ValidationError::InvalidWeight("权重必须大于0".to_string()));
        }
        self.weight = weight;
        Ok(self)
    }

    /// 设置服务实例健康状态
    /// 
    /// 健康状态用于标识服务实例是否可以接收请求。不健康的实例通常会
    /// 被负载均衡器从路由列表中移除，直到它们恢复健康。
    ///
    /// # 参数
    ///
    /// * `healthy` - 新的健康状态
    ///   - `true` - 实例健康，可以接收请求
    ///   - `false` - 实例不健康，不应接收请求
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceInstance;
    ///
    /// let mut instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
    /// 
    /// // 新创建的实例默认为健康状态
    /// assert!(instance.healthy);
    /// 
    /// // 设置为不健康
    /// instance.set_healthy(false);
    /// assert!(!instance.healthy);
    /// 
    /// // 恢复健康状态
    /// instance.set_healthy(true);
    /// assert!(instance.healthy);
    /// ```
    ///
    /// # 注意事项
    ///
    /// * 健康状态通常由健康检查组件管理
    /// * 手动设置健康状态可能会被健康检查结果覆盖
    /// * 不健康的实例不会参与负载均衡
    pub fn set_healthy(&mut self, healthy: bool) {
        self.healthy = healthy;
    }
    
    /// 设置服务分组
    /// 
    /// 服务分组用于对相关的服务实例进行逻辑分组，便于管理和路由。
    /// 分组可以按照业务类型、团队或功能模块来划分。
    ///
    /// # 参数
    ///
    /// * `group` - 新的服务分组，`None` 表示移除分组
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceInstance;
    ///
    /// let mut instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
    /// 
    /// // 设置分组
    /// instance.set_group(Some("user-group".to_string()));
    /// assert_eq!(instance.group, Some("user-group".to_string()));
    /// 
    /// // 移除分组
    /// instance.set_group(None);
    /// assert_eq!(instance.group, None);
    /// ```
    pub fn set_group(&mut self, group: Option<String>) {
        self.group = group;
    }
    
    /// 获取服务分组
    /// 
    /// 返回当前服务实例的分组信息。如果未设置分组，则返回 None。
    ///
    /// # 返回值
    ///
    /// * `Some(&str)` - 服务实例的分组名称
    /// * `None` - 未设置分组
    pub fn get_group(&self) -> Option<&str> {
        self.group.as_deref()
    }
    
    /// 设置命名空间
    /// 
    /// 命名空间用于实现环境隔离，不同命名空间中的服务实例通常不会相互发现。
    /// 常用于区分开发、测试和生产环境。
    ///
    /// # 参数
    ///
    /// * `namespace` - 新的命名空间，`None` 表示移除命名空间
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceInstance;
    ///
    /// let mut instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
    /// 
    /// // 设置命名空间
    /// instance.set_namespace(Some("production".to_string()));
    /// assert_eq!(instance.namespace, Some("production".to_string()));
    /// 
    /// // 移除命名空间
    /// instance.set_namespace(None);
    /// assert_eq!(instance.namespace, None);
    /// ```
    pub fn set_namespace(&mut self, namespace: Option<String>) {
        self.namespace = namespace;
    }
    
    /// 获取命名空间
    /// 
    /// 返回当前服务实例的命名空间信息。如果未设置命名空间，则返回 None。
    ///
    /// # 返回值
    ///
    /// * `Some(&str)` - 服务实例的命名空间
    /// * `None` - 未设置命名空间
    pub fn get_namespace(&self) -> Option<&str> {
        self.namespace.as_deref()
    }
    
    /// 设置环境
    pub fn set_environment(&mut self, environment: Option<String>) {
        self.environment = environment;
    }
    
    /// 获取环境
    pub fn get_environment(&self) -> Option<&str> {
        self.environment.as_deref()
    }
    
    /// 设置集群
    pub fn set_cluster(&mut self, cluster: Option<String>) {
        self.cluster = cluster;
    }
    
    /// 获取集群
    pub fn get_cluster(&self) -> Option<&str> {
        self.cluster.as_deref()
    }
    
    /// 检查是否匹配环境过滤条件
    pub fn matches_environment(&self, env_filter: &EnvironmentFilter) -> bool {
        // 检查命名空间
        if let Some(ref namespace) = env_filter.namespace {
            if self.namespace.as_ref() != Some(namespace) {
                return false;
            }
        }
        
        // 检查分组
        if let Some(ref group) = env_filter.group {
            if self.group.as_ref() != Some(group) {
                return false;
            }
        }
        
        // 检查环境
        if let Some(ref environment) = env_filter.environment {
            if self.environment.as_ref() != Some(environment) {
                return false;
            }
        }
        
        // 检查集群
        if let Some(ref cluster) = env_filter.cluster {
            if self.cluster.as_ref() != Some(cluster) {
                return false;
            }
        }
        
        true
    }
    
    /// 生成完整的服务标识符（包括分组和环境信息）
    pub fn full_service_id(&self) -> String {
        let mut parts = Vec::new();
        
        if let Some(ref namespace) = self.namespace {
            parts.push(format!("ns:{}", namespace));
        }
        
        if let Some(ref group) = self.group {
            parts.push(format!("group:{}", group));
        }
        
        if let Some(ref environment) = self.environment {
            parts.push(format!("env:{}", environment));
        }
        
        if let Some(ref cluster) = self.cluster {
            parts.push(format!("cluster:{}", cluster));
        }
        
        parts.push(self.service_id.clone());
        
        parts.join(":")
    }

    /// 从地址字符串解析服务实例
    /// 地址格式应为：scheme://host:port
    pub fn from_address(service_id: impl Into<String>, address: &str) -> Result<Self, ValidationError> {
        let parts: Vec<&str> = address.splitn(2, "://").collect();
        if parts.len() != 2 {
            return Err(ValidationError::InvalidHost(format!("无效的地址格式: {}", address)));
        }
        
        let scheme = parts[0];
        let host_port = parts[1];
        
        let host_port_parts: Vec<&str> = host_port.split(':').collect();
        if host_port_parts.len() != 2 {
            return Err(ValidationError::InvalidHost(format!("无效的主机端口格式: {}", host_port)));
        }
        
        let host = host_port_parts[0];
        let port = host_port_parts[1].parse().map_err(|_| {
            ValidationError::InvalidPort(format!("无效的端口号: {}", host_port_parts[1]))
        })?;
        
        let instance = ServiceInstance::new(service_id, host, port, scheme);
        instance.validate()?;
        Ok(instance)
    }
}

impl fmt::Display for ServiceInstance {
    /// 格式化显示服务实例信息
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}@{}:{}", self.service_id, self.host, self.port)
    }
}

/// 环境过滤器
///
/// 用于按照命名空间、分组、环境等维度过滤服务实例。该结构体支持多维度的
/// 组合过滤，可以实现精细的服务发现和路由控制。
///
/// # 使用场景
///
/// * 环境隔离 - 区分开发、测试和生产环境
/// * 服务分组 - 对相关服务进行逻辑分组
/// * 多集群部署 - 在不同集群中运行相同服务
/// * 灰度发布 - 基于环境标签控制流量分配
///
/// # 字段说明
///
/// * `namespace` - 命名空间过滤，用于环境隔离
/// * `group` - 服务分组过滤，用于逻辑分组
/// * `environment` - 环境过滤，用于区分环境类型
/// * `cluster` - 集群过滤，用于多集群部署
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::EnvironmentFilter;
///
/// // 创建空过滤器（匹配所有实例）
/// let empty_filter = EnvironmentFilter::new();
///
/// // 创建单一维度过滤器
/// let prod_filter = EnvironmentFilter::new()
///     .with_environment("production");
///
/// // 创建多维度过滤器
/// let complex_filter = EnvironmentFilter::new()
///     .with_namespace("production")
///     .with_group("user-group")
///     .with_environment("prod")
///     .with_cluster("cluster-1");
///
/// // 检查服务实例是否匹配过滤器
/// let instance = ServiceInstance::new("user-service", "127.0.0.1", 8080, "http");
/// let matches = instance.matches_environment(&complex_filter);
/// ```
///
/// # 注意事项
///
/// * 所有过滤条件都是 AND 关系，只有全部匹配才返回 true
/// * `None` 值表示不过滤该维度，相当于通配符
/// * 空过滤器会匹配所有服务实例
/// * 支持序列化和反序列化，可用于网络传输
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct EnvironmentFilter {
    /// 命名空间过滤
    pub namespace: Option<String>,
    /// 分组过滤
    pub group: Option<String>,
    /// 环境过滤
    pub environment: Option<String>,
    /// 集群过滤
    pub cluster: Option<String>,
}

impl EnvironmentFilter {
    /// 创建新的环境过滤器
    pub fn new() -> Self {
        Self::default()
    }
    
    /// 设置命名空间过滤
    pub fn with_namespace(mut self, namespace: impl Into<String>) -> Self {
        self.namespace = Some(namespace.into());
        self
    }
    
    /// 设置分组过滤
    pub fn with_group(mut self, group: impl Into<String>) -> Self {
        self.group = Some(group.into());
        self
    }
    
    /// 设置环境过滤
    pub fn with_environment(mut self, environment: impl Into<String>) -> Self {
        self.environment = Some(environment.into());
        self
    }
    
    /// 设置集群过滤
    pub fn with_cluster(mut self, cluster: impl Into<String>) -> Self {
        self.cluster = Some(cluster.into());
        self
    }
    
    /// 检查是否为空过滤器（没有任何过滤条件）
    pub fn is_empty(&self) -> bool {
        self.namespace.is_none() 
            && self.group.is_none() 
            && self.environment.is_none() 
            && self.cluster.is_none()
    }
}

/// 服务环境配置
/// 用于配置服务的环境隔离策略
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ServiceEnvironmentConfig {
    /// 默认命名空间
    pub default_namespace: String,
    /// 默认分组
    pub default_group: String,
    /// 默认环境
    pub default_environment: String,
    /// 默认集群
    pub default_cluster: String,
    /// 是否启用环境隔离
    pub isolation_enabled: bool,
    /// 是否允许跨环境调用
    pub allow_cross_environment: bool,
}

impl Default for ServiceEnvironmentConfig {
    fn default() -> Self {
        Self {
            default_namespace: "default".to_string(),
            default_group: "DEFAULT_GROUP".to_string(),
            default_environment: "dev".to_string(),
            default_cluster: "default".to_string(),
            isolation_enabled: true,
            allow_cross_environment: false,
        }
    }
}
/// 验证错误枚举类型
///
/// 该枚举定义了在验证服务实例、配置参数和其他数据时可能遇到的各种验证错误。
/// 每个错误都包含详细的错误描述，便于调试和错误处理。
///
/// # 错误类型
///
/// * `InvalidServiceId` - 服务ID验证失败，通常是空字符串或无效格式
/// * `InvalidHost` - 主机地址验证失败，不是有效的IP地址或域名
/// * `InvalidPort` - 端口号验证失败，超出有效范围或为0
/// * `InvalidScheme` - 协议验证失败，不是支持的协议类型
/// * `InvalidWeight` - 权重验证失败，必须大于0
///
/// # 使用场景
///
/// * 服务实例注册时的参数验证
/// * 配置文件加载时的合法性检查
/// * API请求参数的输入验证
/// * 网络连接配置的验证
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::{ValidationError, ServiceInstance};
///
/// // 验证失败的例子
/// let result = ServiceInstance::new("", "127.0.0.1", 8080, "http").validate();
/// match result {
///     Err(ValidationError::InvalidServiceId(msg)) => {
///         println!("服务ID错误: {}", msg);
///     }
///     _ => {}
/// }
///
/// // 主机地址验证失败
/// let result = ServiceInstance::new("service", "invalid-host", 8080, "http").validate();
/// match result {
///     Err(ValidationError::InvalidHost(msg)) => {
///         println!("主机地址错误: {}", msg);
///     }
///     _ => {}
/// }
///
/// // 端口号验证失败
/// let result = ServiceInstance::new("service", "127.0.0.1", 0, "http").validate();
/// match result {
///     Err(ValidationError::InvalidPort(msg)) => {
///         println!("端口号错误: {}", msg);
///     }
///     _ => {}
/// }
/// ```
///
/// # 错误处理最佳实践
///
/// * 在用户输入验证失败时，应该向用户显示清晰的错误消息
/// * 在日志中记录详细的验证错误信息，便于问题排查
/// * 对于可恢复的验证错误，应该提供默认值或修复建议
/// * 在开发环境中，可以输出更详细的验证信息和堆栈跟踪
///
/// # 注意事项
///
/// * 所有验证错误都包含中文错误消息，适合中文用户界面
/// * 错误消息包含具体的错误值，便于定位问题
/// * 支持与ServiceError的自动转换，便于统一错误处理
#[derive(Debug, thiserror::Error)]
pub enum ValidationError {
    #[error("服务ID无效: {0}")]
    InvalidServiceId(String),
    #[error("主机地址无效: {0}")]
    InvalidHost(String),
    #[error("端口号无效: {0}")]
    InvalidPort(String),
    #[error("协议无效: {0}")]
    InvalidScheme(String),
    #[error("权重无效: {0}")]
    InvalidWeight(String),
}

/// HTTP请求数据结构
///
/// 表示一个在微服务架构中发送的HTTP请求。该结构体包含了所有必要的请求信息，
/// 包括目标服务、HTTP方法、请求路径、请求头、请求体和查询参数。
///
/// # 字段说明
///
/// * `service_name` - 目标服务名称，用于服务发现和路由
/// * `method` - HTTP方法（GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS）
/// * `path` - 请求路径，包括路径参数但不包括查询参数
/// * `headers` - HTTP请求头，存储为键值对
/// * `body` - 请求体（可选），以字节数组形式存储
/// * `query_params` - URL查询参数，存储为键值对
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::Request;
/// use std::collections::HashMap;
///
/// // 创建基本请求
/// let mut request = Request::new("user-service", "GET", "/api/users");
///
/// // 添加请求头
/// request.add_header("Content-Type", "application/json");
/// request.add_header("Authorization", "Bearer token123");
///
/// // 添加查询参数
/// request.add_query_param("limit", "10");
/// request.add_query_param("offset", "0");
///
/// // 设置请求体（适用于POST/PUT请求）
/// request.set_body(b"{\"name\":\"John\", \"age\": 30}".to_vec());
/// ```
///
/// # 支持的HTTP方法
///
/// * `GET` - 获取资源
/// * `POST` - 创建资源
/// * `PUT` - 更新资源
/// * `DELETE` - 删除资源
/// * `PATCH` - 部分更新资源
/// * `HEAD` - 获取资源头部信息
/// * `OPTIONS` - 获取支持的方法信息
///
/// # 注意事项
///
/// * 请求体对于GET和HEAD请求通常为空
/// * 请求头名称不区分大小写，但建议使用标准大小写
/// * 支持序列化和反序列化，便于网络传输和持久化
/// * 查询参数会被自动URL编码
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Request {
    /// 目标服务名称
    pub service_name: String,
    /// HTTP方法（GET, POST, PUT, DELETE等）
    pub method: String,
    /// 请求路径
    pub path: String,
    /// HTTP请求头
    pub headers: HashMap<String, String>,
    /// 请求体（可选）
    pub body: Option<Vec<u8>>,
    /// URL查询参数
    pub query_params: HashMap<String, String>,
}

impl Request {
    /// 创建一个新的HTTP请求
    /// 
    /// 该方法创建一个包含基本信息的HTTP请求实例。创建后可以通过其他方法
    /// 添加请求头、查询参数和请求体。
    ///
    /// # 参数
    ///
    /// * `service_name` - 目标服务名称，用于服务发现
    /// * `method` - HTTP方法，支持所有标准HTTP方法
    /// * `path` - 请求路径，应以 `/` 开头（可选）
    ///
    /// # 返回值
    ///
    /// 返回一个新的 `Request` 实例，其中请求头、查询参数和请求体为空。
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::Request;
    ///
    /// // 创建基本的GET请求
    /// let request = Request::new("user-service", "GET", "/api/users");
    /// assert_eq!(request.service_name, "user-service");
    /// assert_eq!(request.method, "GET");
    /// assert_eq!(request.path, "/api/users");
    ///
    /// // 创建POST请求
    /// let request = Request::new("order-service", "POST", "/api/orders");
    ///
    /// // 创建带路径参数的请求
    /// let request = Request::new("user-service", "GET", "/api/users/123");
    /// ```
    pub fn new(
        service_name: impl Into<String>,
        method: impl Into<String>,
        path: impl Into<String>,
    ) -> Self {
        Self {
            service_name: service_name.into(),
            method: method.into(),
            path: path.into(),
            headers: HashMap::new(),
            body: None,
            query_params: HashMap::new(),
        }
    }

    /// 添加请求头
    /// 
    /// HTTP请求头用于传递元数据信息，如内容类型、身份验证、缓存控制等。
    /// 该方法允许添加任意的请求头，如果键名已存在，则会覆盖旧值。
    ///
    /// # 参数
    ///
    /// * `key` - 请求头的名称，不区分大小写
    /// * `value` - 请求头的值
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::Request;
    ///
    /// let mut request = Request::new("api-service", "POST", "/api/data");
    ///
    /// // 添加内容类型
    /// request.add_header("Content-Type", "application/json");
    ///
    /// // 添加身份验证
    /// request.add_header("Authorization", "Bearer eyJ0eXAiOiJKV1QiLi...");
    ///
    /// // 添加自定义头部
    /// request.add_header("X-Request-ID", "req-12345");
    /// request.add_header("User-Agent", "RustCloud/1.0");
    /// ```
    ///
    /// # 常用请求头
    ///
    /// * `Content-Type` - 请求体的MIME类型
    /// * `Authorization` - 身份验证信息
    /// * `Accept` - 客户端可接受的内容类型
    /// * `User-Agent` - 客户端标识
    /// * `X-Request-ID` - 请求追踪标识
    pub fn add_header(&mut self, key: impl Into<String>, value: impl Into<String>) {
        self.headers.insert(key.into(), value.into());
    }

    /// 添加查询参数
    /// 
    /// 查询参数用于在URL中传递参数，通常用于GET请求的过滤、排序、分页等操作。
    /// 参数会被自动URL编码，如果键名已存在，则会覆盖旧值。
    ///
    /// # 参数
    ///
    /// * `key` - 查询参数的名称
    /// * `value` - 查询参数的值
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::Request;
    ///
    /// let mut request = Request::new("user-service", "GET", "/api/users");
    ///
    /// // 添加分页参数
    /// request.add_query_param("page", "1");
    /// request.add_query_param("size", "20");
    ///
    /// // 添加过滤参数
    /// request.add_query_param("status", "active");
    /// request.add_query_param("role", "admin");
    ///
    /// // 添加排序参数
    /// request.add_query_param("sort", "created_at");
    /// request.add_query_param("order", "desc");
    ///
    /// // 最终URL将会是: /api/users?page=1&size=20&status=active&role=admin&sort=created_at&order=desc
    /// ```
    ///
    /// # 注意事项
    ///
    /// * 参数值会被自动URL编码，不需要手动编码
    /// * 空值和特殊字符都会被正确处理
    /// * 对于POST/PUT请求，建议将数据放在请求体中而不是查询参数
    pub fn add_query_param(&mut self, key: impl Into<String>, value: impl Into<String>) {
        self.query_params.insert(key.into(), value.into());
    }

    /// 设置请求体
    /// 
    /// 请求体包含要发送给服务器的数据，通常用于POST、PUT和PATCH请求。
    /// 数据以字节数组形式存储，支持任意类型的数据（文本、二进制等）。
    ///
    /// # 参数
    ///
    /// * `body` - 请求体数据，以字节数组形式传入
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::Request;
    ///
    /// let mut request = Request::new("user-service", "POST", "/api/users");
    ///
    /// // 设置JSON数据
    /// let json_data = r#"{
    ///     "name": "John Doe",
    ///     "email": "john@example.com",
    ///     "age": 30
    /// }"#;
    /// request.add_header("Content-Type", "application/json");
    /// request.set_body(json_data.as_bytes().to_vec());
    ///
    /// // 设置表单数据
    /// let form_data = "name=John&email=john@example.com&age=30";
    /// request.add_header("Content-Type", "application/x-www-form-urlencoded");
    /// request.set_body(form_data.as_bytes().to_vec());
    ///
    /// // 设置二进制数据
    /// let binary_data = vec![0x48, 0x65, 0x6c, 0x6c, 0x6f]; // "Hello" in bytes
    /// request.set_body(binary_data);
    ///
    /// // 清空请求体
    /// request.set_body(Vec::new());
    /// ```
    ///
    /// # 注意事项
    ///
    /// * 请确保设置了正确的 `Content-Type` 请求头
    /// * GET和HEAD请求通常不应该包含请求体
    /// * 对于大文件，建议使用流式上传或分块上传
    /// * 请求体大小可能受到服务器限制
    pub fn set_body(&mut self, body: Vec<u8>) {
        self.body = Some(body);
    }
}

/// HTTP响应数据结构
///
/// 表示一个在微服务架构中接收到的HTTP响应。该结构体包含了响应的所有关键信息，
/// 包括状态码、响应头和响应体。支持所有标准的HTTP状态码和响应类型。
///
/// # 字段说明
///
/// * `status` - HTTP状态码，表示请求处理结果
/// * `headers` - HTTP响应头，存储为键值对
/// * `body` - 响应体（可选），以字节数组形式存储
///
/// # 状态码分类
///
/// * **1xx 信息性响应** - 请求已接收，继续处理
/// * **2xx 成功响应** - 请求已成功处理
/// * **3xx 重定向** - 需要进一步操作才能完成请求
/// * **4xx 客户端错误** - 请求包含错误语法或无法完成
/// * **5xx 服务器错误** - 服务器在处理请求的过程中发生错误
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::Response;
///
/// // 创建成功响应
/// let mut response = Response::new(200);
/// response.add_header("Content-Type", "application/json");
/// response.set_body(b"{\"message\": \"success\"}".to_vec());
///
/// // 创建错误响应
/// let mut error_response = Response::new(404);
/// error_response.add_header("Content-Type", "application/json");
/// error_response.set_body(b"{\"error\": \"Not Found\"}".to_vec());
///
/// // 检查响应是否成功
/// assert!(response.is_success());
/// assert!(!error_response.is_success());
/// ```
///
/// # 常用状态码
///
/// * `200 OK` - 请求成功
/// * `201 Created` - 资源创建成功
/// * `204 No Content` - 请求成功但无内容返回
/// * `400 Bad Request` - 请求参数错误
/// * `401 Unauthorized` - 未授权
/// * `404 Not Found` - 资源不存在
/// * `500 Internal Server Error` - 服务器内部错误
///
/// # 注意事项
///
/// * 支持序列化和反序列化，便于网络传输
/// * 响应体可以为空，特别是204和304状态码
/// * 响应头不区分大小写，但建议使用标准大小写
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Response {
    /// HTTP状态码
    pub status: u16,
    /// HTTP响应头
    pub headers: HashMap<String, String>,
    /// 响应体（可选）
    pub body: Option<Vec<u8>>,
}

impl Response {
    /// 创建一个新的HTTP响应
    /// 
    /// 该方法创建一个包含指定状态码的HTTP响应实例。创建后可以通过其他方法
    /// 添加响应头和响应体。
    ///
    /// # 参数
    ///
    /// * `status` - HTTP状态码，应符合HTTP规范（1xx-5xx）
    ///
    /// # 返回值
    ///
    /// 返回一个新的 `Response` 实例，其中响应头和响应体为空。
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::Response;
    ///
    /// // 创建成功响应
    /// let success_response = Response::new(200);
    /// assert!(success_response.is_success());
    ///
    /// // 创建已创建响应
    /// let created_response = Response::new(201);
    /// assert!(created_response.is_success());
    ///
    /// // 创建客户端错误响应
    /// let bad_request_response = Response::new(400);
    /// assert!(!bad_request_response.is_success());
    ///
    /// // 创建服务器错误响应
    /// let server_error_response = Response::new(500);
    /// assert!(!server_error_response.is_success());
    /// ```
    pub fn new(status: u16) -> Self {
        Self {
            status,
            headers: HashMap::new(),
            body: None,
        }
    }

    /// 添加响应头
    /// 
    /// HTTP响应头用于传递元数据信息，如内容类型、缓存控制、跨域配置等。
    /// 该方法允许添加任意的响应头，如果键名已存在，则会覆盖旧值。
    ///
    /// # 参数
    ///
    /// * `key` - 响应头的名称，不区分大小写
    /// * `value` - 响应头的值
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::Response;
    ///
    /// let mut response = Response::new(200);
    ///
    /// // 添加内容类型
    /// response.add_header("Content-Type", "application/json");
    ///
    /// // 添加缓存控制
    /// response.add_header("Cache-Control", "no-cache");
    ///
    /// // 添加跨域头部
    /// response.add_header("Access-Control-Allow-Origin", "*");
    ///
    /// // 添加自定义头部
    /// response.add_header("X-Response-Time", "123ms");
    /// ```
    ///
    /// # 常用响应头
    ///
    /// * `Content-Type` - 响应体的MIME类型
    /// * `Content-Length` - 响应体的字节长度
    /// * `Cache-Control` - 缓存控制指令
    /// * `Location` - 重定向目标URL（适用于3xx状态码）
    /// * `Set-Cookie` - 设置Cookie
    pub fn add_header(&mut self, key: impl Into<String>, value: impl Into<String>) {
        self.headers.insert(key.into(), value.into());
    }

    /// 设置响应体
    /// 
    /// 响应体包含要返回给客户端的数据，可以是文本、JSON、XML、二进制数据等。
    /// 数据以字节数组形式存储，支持任意类型的内容。
    ///
    /// # 参数
    ///
    /// * `body` - 响应体数据，以字节数组形式传入
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::Response;
    ///
    /// let mut response = Response::new(200);
    ///
    /// // 返回JSON数据
    /// let json_data = r#"{
    ///     "id": 123,
    ///     "name": "John Doe",
    ///     "email": "john@example.com"
    /// }"#;
    /// response.add_header("Content-Type", "application/json");
    /// response.set_body(json_data.as_bytes().to_vec());
    ///
    /// // 返回纯文本
    /// response.add_header("Content-Type", "text/plain");
    /// response.set_body("Hello, World!".as_bytes().to_vec());
    ///
    /// // 返回空内容（适用于204状态码）
    /// let empty_response = Response::new(204);
    /// // 不需要设置响应体
    /// ```
    ///
    /// # 注意事项
    ///
    /// * 请确保设置了正确的 `Content-Type` 响应头
    /// * 204 No Content 和 304 Not Modified 状态码通常不应该包含响应体
    /// * 对于大文件，建议使用流式响应或分块传输
    pub fn set_body(&mut self, body: Vec<u8>) {
        self.body = Some(body);
    }

    /// 检查响应是否成功（2xx状态码）
    /// 
    /// 该方法根据HTTP规范判断响应是否表示成功。所有200-299范围内的状态码
    /// 都被视为成功响应。
    ///
    /// # 返回值
    ///
    /// * `true` - 响应状态码在200-299范围内，表示成功
    /// * `false` - 响应状态码不在200-299范围内，表示失败
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::Response;
    ///
    /// // 成功响应
    /// let ok_response = Response::new(200);
    /// assert!(ok_response.is_success());
    ///
    /// let created_response = Response::new(201);
    /// assert!(created_response.is_success());
    ///
    /// let no_content_response = Response::new(204);
    /// assert!(no_content_response.is_success());
    ///
    /// // 失败响应
    /// let not_found_response = Response::new(404);
    /// assert!(!not_found_response.is_success());
    ///
    /// let server_error_response = Response::new(500);
    /// assert!(!server_error_response.is_success());
    ///
    /// // 重定向响应（不被视为成功）
    /// let redirect_response = Response::new(302);
    /// assert!(!redirect_response.is_success());
    /// ```
    ///
    /// # 状态码范围
    ///
    /// * **2xx 成功** - 200 OK, 201 Created, 204 No Content, 206 Partial Content
    /// * **非2xx** - 1xx 信息, 3xx 重定向, 4xx 客户端错误, 5xx 服务器错误
    pub fn is_success(&self) -> bool {
        self.status >= 200 && self.status < 300
    }
}

/// 服务信息数据结构
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ServiceInfo {
    /// 服务名称
    pub name: String,
    /// 服务版本
    pub version: String,
    /// 服务分组（可选）
    pub group: Option<String>,
    /// 命名空间（可选）
    pub namespace: Option<String>,
}

impl ServiceInfo {
    /// 创建新的服务信息
    pub fn new(name: impl Into<String>, version: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            version: version.into(),
            group: None,
            namespace: None,
        }
    }
}



/// 负载均衡策略枚举
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum LoadBalancerStrategy {
    /// 轮询算法
    RoundRobin,
    /// 随机算法
    Random,
    /// 加权轮询算法
    WeightedRoundRobin,
    /// 一致性哈希算法
    ConsistentHash,
}

impl fmt::Display for LoadBalancerStrategy {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            LoadBalancerStrategy::RoundRobin => write!(f, "轮询"),
            LoadBalancerStrategy::Random => write!(f, "随机"),
            LoadBalancerStrategy::WeightedRoundRobin => write!(f, "加权轮询"),
            LoadBalancerStrategy::ConsistentHash => write!(f, "一致性哈希"),
        }
    }
}

// CircuitBreakerConfig 已移至 rustcloud-circuit-breaker 模块

/// 注册中心类型枚举
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum RegistryType {
    /// Nacos注册中心
    Nacos,
    /// Consul注册中心
    Consul,
    /// Eureka注册中心
    Eureka,
}

impl fmt::Display for RegistryType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            RegistryType::Nacos => write!(f, "Nacos"),
            RegistryType::Consul => write!(f, "Consul"),
            RegistryType::Eureka => write!(f, "Eureka"),
        }
    }
}

// RegistryConfig 已移至 rustcloud-registry 模块

// LoadBalancerConfig 已移至 rustcloud-loadbalancer 模块

// TransportConfig 已移至 rustcloud-transport 模块

// LoggingConfig 已移至 rustcloud-logging 模块

// LogFormat, LogOutput 已移至 rustcloud-logging 模块

// GatewayConfig, RouteConfig, AuthConfig, RateLimitConfig, FilterConfig 已移至 rustcloud-gateway 模块



/// 应用配置数据结构（临时保留，待统一至 rustcloud-config）
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ApplicationConfig {
    /// 应用名称
    pub name: String,
    /// 应用版本
    pub version: String,
    /// 服务分组（可选）
    pub group: Option<String>,
    /// 命名空间（可选）
    pub namespace: Option<String>,
    /// 服务端口号
    pub port: u16,
    /// 服务绑定地址（可选）
    pub host: Option<String>,
    /// 应用元数据
    pub metadata: HashMap<String, String>,
}

impl Default for ApplicationConfig {
    fn default() -> Self {
        Self {
            name: "rustcloud-app".to_string(),
            version: "1.0.0".to_string(),
            group: None,
            namespace: None,
            port: 8080,
            host: Some("0.0.0.0".to_string()),
            metadata: HashMap::new(),
        }
    }
}

// ApplicationConfig 已移至 rustcloud-config 模块

/// 熔断器状态枚举
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash, Default)]
pub enum CircuitBreakerState {
    #[default]
    Closed,
    Open,
    HalfOpen,
}

/// 熔断器指标数据结构
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct CircuitBreakerMetrics {
    pub total_calls: u64,
    pub failed_calls: u64,
    pub success_calls: u64,
    pub last_failure_time: Option<std::time::SystemTime>,
    pub state: CircuitBreakerState,
}

/// 服务调用结果类型别名
pub type ServiceResult<T> = Result<T, ServiceError>;

/// 服务错误枚举类型
///
/// 该枚举涵盖了在微服务架构中服务注册、发现、调用过程中可能遇到的各种错误。
/// 每个错误类型都包含详细的错误信息，便于调试和问题追踪。
///
/// # 错误分类
///
/// ## 服务发现类错误
/// * `ServiceNotFound` - 指定的服务不存在或未注册
/// * `NoAvailableInstances` - 服务存在但没有可用的实例
/// * `RegistryError` - 注册中心操作失败
///
/// ## 网络通信类错误
/// * `NetworkError` - 网络连接或通信失败
/// * `TimeoutError` - 请求超时
/// * `SerializationError` - 数据序列化/反序列化失败
///
/// ## 服务治理类错误
/// * `LoadBalancerError` - 负载均衡策略执行失败
/// * `CircuitBreakerOpen` - 熔断器已打开，服务不可用
///
/// ## 系统配置类错误
/// * `ConfigurationError` - 配置参数错误或缺失
/// * `ValidationError` - 数据验证失败
///
/// ## 其他类错误
/// * `MetricsError` - 指标收集或上报失败
/// * `NotImplemented` - 功能未实现或不支持
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::{ServiceError, ServiceResult};
///
/// // 服务发现错误处理
/// fn handle_service_call_error(error: ServiceError) {
///     match error {
///         ServiceError::ServiceNotFound(service_name) => {
///             println!("服务不存在: {}", service_name);
///             // 可以记录日志或返回默认响应
///         }
///         ServiceError::NoAvailableInstances(service_name) => {
///             println!("服务无可用实例: {}", service_name);
///             // 可以尝试其他区域或降级处理
///         }
///         ServiceError::CircuitBreakerOpen(service_name) => {
///             println!("服务熔断器已打开: {}", service_name);
///             // 执行降级策略
///         }
///         ServiceError::NetworkError(msg) => {
///             println!("网络错误: {}", msg);
///             // 可以尝试重试或切换网络
///         }
///         _ => {
///             println!("其他错误: {}", error);
///         }
///     }
/// }
///
/// // 错误类型判断
/// fn is_retryable_error(error: &ServiceError) -> bool {
///     error.is_network_error() || 
///     matches!(error, ServiceError::NoAvailableInstances(_))
/// }
/// ```
///
/// # 错误处理最佳实践
///
/// ## 重试策略
/// * 网络错误和超时错误通常可以重试
/// * 熔断器打开后不应该立即重试，应等待恢复
/// * 配置错误和验证错误通常不可重试
///
/// ## 降级处理
/// * 服务不可用时应该提供降级响应
/// * 可以返回缓存数据或默认值
/// * 应该记录降级事件便于监控
///
/// ## 日志记录
/// * 所有错误都应该记录到适当的日志级别
/// * 包含充分的上下文信息和错误详情
/// * 可以添加追踪ID便于问题跟踪
///
/// # 注意事项
///
/// * 错误消息包含中文描述，适合中文用户界面
/// * 支持与标准库错误类型的自动转换
/// * 实现了Display和Error trait，便于集成其他错误处理库
/// * 可以与? 操作符配合使用，实现错误传播
#[derive(Debug, thiserror::Error)]
pub enum ServiceError {
    #[error("服务未找到: {0}")]
    ServiceNotFound(String),
    
    #[error("服务无可用实例: {0}")]
    NoAvailableInstances(String),
    
    #[error("网络错误: {0}")]
    NetworkError(String),
    
    #[error("序列化错误: {0}")]
    SerializationError(String),
    
    #[error("配置错误: {0}")]
    ConfigurationError(String),
    
    #[error("注册中心错误: {0}")]
    RegistryError(String),
    
    #[error("负载均衡错误: {0}")]
    LoadBalancerError(String),
    
    #[error("熔断器已打开，服务: {0}")]
    CircuitBreakerOpen(String),
    
    #[error("超时错误: {0}")]
    TimeoutError(String),
    
    #[error("指标收集错误: {0}")]
    MetricsError(String),
    
    #[error("告警系统错误: {0}")]
    AlertingError(String),
    
    #[error("追踪系统错误: {0}")]
    TracingError(String),
    
    #[error("配置错误: {0}")]
    ConfigError(String),
    
    #[error("内部错误: {0}")]
    InternalError(String),
    
    #[error("功能未实现: {0}")]
    NotImplemented(String),
    
    #[error("依赖注入错误: {0}")]
    DIError(String),
    
    #[error("验证错误: {0}")]
    ValidationError(#[from] ValidationError),
}

impl ServiceError {
    /// 判断错误是否为网络相关错误
    /// 
    /// 该方法用于识别与网络通信相关的错误类型，包括网络连接失败和超时错误。
    /// 网络相关错误通常是临时性的，可以通过重试或切换网络来解决。
    ///
    /// # 返回值
    ///
    /// * `true` - 错误属于网络相关错误（NetworkError 或 TimeoutError）
    /// * `false` - 错误不属于网络相关错误
    ///
    /// # 网络错误类型
    ///
    /// * `NetworkError` - 网络连接失败、DNS解析失败、连接被拒绝等
    /// * `TimeoutError` - 请求超时、连接超时、读取超时等
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceError;
    ///
    /// let network_error = ServiceError::NetworkError("连接被拒绝".to_string());
    /// assert!(network_error.is_network_error());
    ///
    /// let timeout_error = ServiceError::TimeoutError("请求超时".to_string());
    /// assert!(timeout_error.is_network_error());
    ///
    /// let config_error = ServiceError::ConfigurationError("配置无效".to_string());
    /// assert!(!config_error.is_network_error());
    /// ```
    ///
    /// # 使用场景
    ///
    /// * 实现重试逻辑：对网络错误进行自动重试
    /// * 错误分类统计：区分网络问题和业务逻辑问题
    /// * 服务降级：网络错误时使用缓存或默认值
    /// * 监控告警：网络错误率过高时触发告警
    pub fn is_network_error(&self) -> bool {
        matches!(self, ServiceError::NetworkError(_) | ServiceError::TimeoutError(_))
    }

    /// 判断错误是否为服务未找到错误
    /// 
    /// 该方法用于识别服务发现过程中的服务不存在错误。当尝试调用一个
    /// 未注册或已下线的服务时，会产生此类错误。
    ///
    /// # 返回值
    ///
    /// * `true` - 错误属于服务未找到错误（ServiceNotFound）
    /// * `false` - 错误不属于服务未找到错误
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceError;
    ///
    /// let not_found_error = ServiceError::ServiceNotFound("user-service".to_string());
    /// assert!(not_found_error.is_service_not_found());
    ///
    /// let network_error = ServiceError::NetworkError("连接失败".to_string());
    /// assert!(!network_error.is_service_not_found());
    /// ```
    ///
    /// # 处理策略
    ///
    /// * 检查服务注册状态：确认服务是否正确注册
    /// * 服务降级：使用替代服务或返回默认响应
    /// * 错误上报：记录服务发现失败事件
    /// * 重试策略：短时间内不建议重试，应该检查服务状态
    pub fn is_service_not_found(&self) -> bool {
        matches!(self, ServiceError::ServiceNotFound(_))
    }

    /// 判断错误是否为熔断器打开错误
    /// 
    /// 该方法用于识别熔断器保护机制触发的错误。当服务调用失败率超过阈值时，
    /// 熔断器会打开，阻止后续调用以保护下游服务。
    ///
    /// # 返回值
    ///
    /// * `true` - 错误属于熔断器打开错误（CircuitBreakerOpen）
    /// * `false` - 错误不属于熔断器打开错误
    ///
    /// # 熔断器机制
    ///
    /// 熔断器有三种状态：
    /// * **关闭状态**：正常处理请求
    /// * **打开状态**：拒绝所有请求，快速失败
    /// * **半开状态**：允许少量请求测试服务恢复情况
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceError;
    ///
    /// let circuit_error = ServiceError::CircuitBreakerOpen("user-service".to_string());
    /// assert!(circuit_error.is_circuit_breaker_open());
    ///
    /// let timeout_error = ServiceError::TimeoutError("请求超时".to_string());
    /// assert!(!timeout_error.is_circuit_breaker_open());
    /// ```
    ///
    /// # 处理策略
    ///
    /// * **立即降级**：不要重试，直接执行降级逻辑
    /// * **监控恢复**：等待熔断器自动恢复到半开状态
    /// * **服务替代**：使用备用服务或缓存数据
    /// * **快速失败**：避免级联故障，快速返回错误响应
    pub fn is_circuit_breaker_open(&self) -> bool {
        matches!(self, ServiceError::CircuitBreakerOpen(_))
    }
    
    /// 判断错误是否为超时错误
    /// 
    /// 该方法专门用于识别请求超时错误。超时错误是网络错误的一种特殊类型，
    /// 通常表示服务响应时间过长或网络延迟过高。
    ///
    /// # 返回值
    ///
    /// * `true` - 错误属于超时错误（TimeoutError）
    /// * `false` - 错误不属于超时错误
    ///
    /// # 超时类型
    ///
    /// * **连接超时**：建立TCP连接时间过长
    /// * **读取超时**：等待服务响应时间过长
    /// * **写入超时**：发送请求数据时间过长
    /// * **总体超时**：整个请求处理时间超过限制
    ///
    /// # 使用示例
    ///
    /// ```rust
    /// use rustcloud_core::ServiceError;
    ///
    /// let timeout_error = ServiceError::TimeoutError("请求超时: 5000ms".to_string());
    /// assert!(timeout_error.is_timeout_error());
    /// 
    /// // 超时错误也是网络错误的一种
    /// assert!(timeout_error.is_network_error());
    ///
    /// let config_error = ServiceError::ConfigurationError("配置无效".to_string());
    /// assert!(!config_error.is_timeout_error());
    /// ```
    ///
    /// # 处理策略
    ///
    /// * **调整超时时间**：根据服务特性调整超时阈值
    /// * **重试机制**：使用指数退避算法重试
    /// * **服务降级**：超时时返回缓存或默认值
    /// * **性能监控**：分析超时原因，优化服务性能
    /// * **负载均衡**：将请求路由到响应更快的实例
    pub fn is_timeout_error(&self) -> bool {
        matches!(self, ServiceError::TimeoutError(_))
    }
}

/// 从标准库I/O错误自动转换为ServiceError
/// 
/// 该实现允许将标准库的 `std::io::Error` 自动转换为 `ServiceError::NetworkError`。
/// 这样可以简化错误处理代码，使用 `?` 操作符进行错误传播。
///
/// # 转换逻辑
///
/// * 将I/O错误的错误信息转换为字符串
/// * 统一归类为网络错误类型
/// * 保留原始错误的描述信息
///
/// # 常见I/O错误类型
///
/// * **连接被拒绝** - `Connection refused`
/// * **连接超时** - `Connection timed out`
/// * **网络不可达** - `Network is unreachable`
/// * **地址已在使用** - `Address already in use`
/// * **权限被拒绝** - `Permission denied`
/// * **断开的管道** - `Broken pipe`
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::{ServiceError, ServiceResult};
/// use std::fs::File;
///
/// fn read_config_file() -> ServiceResult<String> {
///     // 这里如果文件不存在，会自动转换为ServiceError
///     let content = std::fs::read_to_string("config.toml")?;
///     Ok(content)
/// }
///
/// // 使用示例
/// match read_config_file() {
///     Ok(config) => println!("配置文件内容: {}", config),
///     Err(ServiceError::NetworkError(msg)) => {
///         println!("文件读取错误: {}", msg);
///     }
///     Err(other) => println!("其他错误: {}", other),
/// }
/// ```
///
/// # 注意事项
///
/// * 并非所有I/O错误都是网络错误，但为了简化处理，统一归类为网络错误
/// * 如果需要更精确的错误分类，可以在转换前检查I/O错误的类型
/// * 转换后会丢失原始的 `std::io::Error` 类型信息
impl From<std::io::Error> for ServiceError {
    fn from(error: std::io::Error) -> Self {
        ServiceError::NetworkError(error.to_string())
    }
}

/// 从serde_json错误自动转换为ServiceError
/// 
/// 该实现允许将 `serde_json::Error` 自动转换为 `ServiceError::SerializationError`。
/// 这在处理JSON序列化/反序列化操作时非常有用，可以统一错误处理流程。
///
/// # 转换逻辑
///
/// * 将JSON错误的错误信息转换为字符串
/// * 归类为序列化错误类型
/// * 保留原始错误的详细描述
///
/// # 常见JSON错误类型
///
/// * **语法错误** - JSON格式不正确
/// * **类型错误** - 字段类型不匹配
/// * **缺少必需字段** - 反序列化时缺少必需的字段
/// * **未知字段** - 包含未定义的字段（取决于反序列化配置）
/// * **数值溢出** - 数值超出目标类型范围
/// * **UTF-8编码错误** - 字符串编码问题
///
/// # 使用示例
///
/// ```rust
/// use rustcloud_core::{ServiceError, ServiceResult, ServiceInstance};
/// use serde_json;
///
/// fn parse_service_instance(json_str: &str) -> ServiceResult<ServiceInstance> {
///     // 如果JSON解析失败，会自动转换为ServiceError
///     let instance: ServiceInstance = serde_json::from_str(json_str)?;
///     Ok(instance)
/// }
///
/// fn serialize_service_instance(instance: &ServiceInstance) -> ServiceResult<String> {
///     // 如果JSON序列化失败，会自动转换为ServiceError  
///     let json_str = serde_json::to_string(instance)?;
///     Ok(json_str)
/// }
///
/// // 使用示例
/// let json = r#"{"service_id":"user-service","host":"127.0.0.1"}"#;
/// match parse_service_instance(json) {
///     Ok(instance) => println!("解析成功: {:?}", instance),
///     Err(ServiceError::SerializationError(msg)) => {
///         println!("JSON解析错误: {}", msg);
///     }
///     Err(other) => println!("其他错误: {}", other),
/// }
/// ```
///
/// # 错误处理建议
///
/// * **输入验证**: 在反序列化前验证JSON格式和必需字段
/// * **默认值**: 对于可选字段，提供合理的默认值
/// * **错误恢复**: 对于部分字段解析失败，可以尝试使用默认值继续
/// * **日志记录**: 记录详细的序列化错误信息，便于调试
///
/// # 性能考虑
///
/// * JSON错误转换的性能开销很小
/// * 错误信息会被复制，避免在高频场景下频繁转换
/// * 可以考虑使用 `serde_json::from_slice` 提高性能
impl From<serde_json::Error> for ServiceError {
    fn from(error: serde_json::Error) -> Self {
        ServiceError::SerializationError(error.to_string())
    }
}